Bank Card Transfer

Overview

This interface allows merchants to transfer funds from their account to a specified bank card account.

Order Status

Status	Description
CREATED	Order created
SUCCESS	Transfer completed
FAILURE	Transfer failed
BANK_FAIL	Bank declined

API URL

UAT Environment: https://uat.test2pay.com/sgs/api/transfer/placeTransferToBankCard
Production Environment: https://api.payby.com/sgs/api/transfer/placeTransferToBankCard

Request

HTTP Headers

Attributes

Content-Language String
- Language in which the response message will be used.
- Currently, only English is supported.
- Example value: en
- Maximum length: 10
Content-Type String Required
- Media type of the request body.
- Required for operations with a request body.
- Format: application/<format> (e.g., application/json)
- Example value: application/json
sign String Required
- Request signature using private-key cryptography.
- Ensures the payment gateway can verify the request origin.
Partner-Id String Required
- Merchant ID of your account.
- Example value: 200001200101
- Maximum length: 12

HTTP Body

requestTime Timestamp Required
- Time the request was initiated.
- Example value: 1581493898000
bizContent:
Attributes
- accountHolderType String(16) Required
  Account holder type: INDIVIDUAL or CORPORATE
  Example value: INDIVIDUAL
- merchantOrderNo String(64) Required
  Unique order identifier from the merchant.
  Example value: Me23484
- firstName String(50)
  Encrypted field. Account holder's first name.
  Required when accountHolderType is INDIVIDUAL
- lastName String(50)
  Encrypted field. Account holder's last name.
  Required when accountHolderType is INDIVIDUAL
- middleName String(50)
  Encrypted field. Account holder's middle name.
- companyName String(50)
  Encrypted field. Company name.
  Required when accountHolderType is CORPORATE.
  Must be a valid legal name. Cannot be a single character, all numeric, or all punctuation.
  Example value: Liwa Street off Khaliffa Street
- amount Money Required
  Amount to transfer.
  Example value: 12.34
- memo String(50)
  Transfer description or note.
  Example value: Bonus
- notifyUrl String(200)
  URL to receive transfer status notifications.
- expiryYear String(4) Required
  Encrypted field. Card expiration year.
  Must be current year or later.
  Example value: 2025
- expiryMonth String(2) Required
  Encrypted field. Card expiration month (1–12).
  Combined year and month must be current month or later.
  Example value: 12
- cardNumber String(50) Required
  Encrypted field. Card number (12–19 digits, numeric only).

Request Sample

{
    "bizContent": {
        "accountHolderType": "INDIVIDUAL",
        "amount": {
            "amount": 0.1,
            "currency": "AED"
        },
        "cardNumber": "aJwgWWe27+/d1e5B8jOhcKdW+cfMteX4mNwmBPvYGWDcXWuMWHKxwdQ89L0p6mij4Bu1xzwLbYzj/4Ou/hmwQrQ26/thcw4Ya1cDlPDu0EDjIMHdOk0INeOv4pueJohEzVkG3RpJdFadjKkgQwuhZmdyIX7b7QhDVegMrf18WzFcDdkTS7UA8/oQ96+ybzSx7uXWsN4xaWFBLnv0bJEYDFxgwSiqJD2EiqUtMTy4iEqXRE5kzlRZfA17jzXk4cCZ1nLrTnLIvivoCWFmw4A36e0ELZ5Jn506lFm5rZnd2aMWJN7OPCR6L4IA+7K5jHlN7QWdPQtNJBrSVOu0/3uujA==",
        "expiryMonth": "S9jFGF1bHU0nOKfLPGDy+euUn2IJVv7v/qiSF2P6GaD8eFLcKs+cJ6D9ou6T60xPA39UyNRnSwBosqbnh5eCD0Rw+jQmTFr72qeqXSqkXFFg/PNIc30VP3l1IyEzJhk4XJ0GQS09kZzs6CEFhb23BWhsSpuWGYba/BOYombxGhaA5td249ZI1G1VbTo5rIxPQjpghJhO9n/iPI0T2dpXE3RuJNeoxOCo2Iz4nhYvmazGuNtncoq2aQcng1Kf6BWb/LmoW2Xz2e3k87YAOcrov+7cm3vh6Af/Wrpk1tNPtN9dAeIYK4rK8gxWHYvn45YFF6HMaZsnFphJ3iDsUca/rg==",
        "expiryYear": "MK858D0uyjePVnBrRGO3qmiLcXLxxrzcdWZjoCqgozrWkzmCcVX3ncUi9RsZwlbTAJIPI0FsXrF9o40Kt7y3SwyjpnGD2uqvv2KkW+ntzGDCUN6jmv/t7QHFEvN5xTZVsf4sA8IMLae6zVprGfYbUjyvZrje2RFATuexZ5kKdesn7Sbzf9Uo1yKCysGtAe2wRQ4EzsXYPqttnl2mWOJ7vlxbTeMiWPCbONvDvhCRN8XhhPq0gJjLhi2xnMuIKHNe7xdZ0XqpGO81MKWqz4Xd5Z97Glsb9Qpa4G3+t6DyzGRJz9v2b8fuJw7D71w1WQDa1mdEhU5c1iwp1jXIZ2Qxhg==",
        "firstName": "HYtBz0aDVZ1GCzyov+B+OViYJ5pQg8B64RNwaxdPMqeTpY3PY4pAzsUHJD8+0SNKI5JF74lopEYIJLxCCiC5cUAJZayKSWMKis7N6y6vAi6s3/WVGg7tS2DJsE/LnKiYAkFkoBDfDhiIVTaBD38ubDT9X3BSPP1fCR/6+m5MyQpQEGRFdan/saF6h9vbdMBEW1N3BCKWvWOREy7lesJlQEg2kMIiaePWilHdzS+qiQGyiXiNze+pKZaamReX2RdJPcF/9rs1KVeCifF+aCejX81f1n8WnlywLIAlUKroF04YNAoPxSotmcwlfvBmHZP2Y+xbn1mJC8GkngOB1IcHvw==",
        "lastName": "FKCYj94zTP/mhGxlqF5SNAwYAx4kVGPgIHi4KdzQ+qmi2ND9iBPvQ5yCygCyxPlwpOdaDjb4zgF+fP6PjIwmFr+284opZVHgMQLCfiX0NRqFXNk6cjIpEmVRFQW5hysATEkZ5bA5slb7WzJACwuuTi/a3gzAsDxwHOdomPl67d1SGypb1nD7DCChGTyn/492diQwIZGeXBewywlyb5NfU/f2f68lMQA82C5eIEmOvM8iLSVjnMARW92BKuTdjhYW6JVJHuUdSG91A1X+GCap5SUklO0LYaXE/lOi+bPxg/KXzARhw4JEpIexV/6IP5hJv1LAq3KjCqo7tjpl6TJ6Gw==",
        "memo": "Bonus",
        "merchantOrderNo": "7a5b47a4-1824-4a4d-b581-9b0ebd5dd436",
        "middleName": "XAvhTN+7oWSj34hxLf6vQsoiPlFn5ysiAAXDasyxTO6w8BearyGSZfnQajtYO2cNSHgmFjXeJbJ7e+YiB5GsWHeVAU0D4tihJ3Yv1VwOoeataGwiBd/mnJ6m/8wK5LWhTBY18Vr5zpjVHTvheH3dMW7t6LucJ/dynKVx08DD0S+YkW+kakICDzCkZYQCXPhuPlMlQNjxTCL2maUSVj2VjzohY7ErRJAy8JHygv8XF0LoE57F3dauoBV9y/hnkuhI/WrxV63wtDtrh/gsFkJ04S/mSiYdzAEOiXkml37Qa5xr0qeBu6XgO5PWo3S7HJCLbe5YO71klDypccmEIxuylA==",
        "notifyUrl": "http://yoursite.com/api/notification"
    },
    "requestTime": 1741917446102
}

Response

HTTP Headers

Attributes

applyStatus String(16) Required
- Request status result.
- Example value: SUCCESS
- Possible values:
  - SUCCESS: Application successful
  - FAIL: Application failed
  - ERROR: Exception occurred
code String(10) Required
- Return error code.
- Example value: 0
msg String(200)
- Return message.

HTTP Body

transferBankCardOrder TransferBankCardOrder Required
- Complete transfer order details.

TransferBankCardOrder:

Attributes

requestTime Timestamp(3) Required
- Request time passed by the merchant when placing the order.
- Example value: 1581493898000
merchantOrderNo String(64) Required
- Merchant's reference number for tracking the request.
- Example value: S10000
orderNo String(32) Required
- PayBy's unique identification number of the order.
- Example value: O1000
product String(200) Required
- Product name of the API method used in the order.
- Example value: Transfer Bank Card
status String Required
- Status of the order.
- Possible values: CREATED, SUCCESS, FAILURE, BANK_FAIL
amount Money Required
- Amount to be transferred.
accountHolderType String(16) Required
- Account holder type: INDIVIDUAL or CORPORATE
- Example value: INDIVIDUAL
firstName String(200)
- SHA256 of original text. Required if accountHolderType is INDIVIDUAL.
lastName String(200)
- SHA256 of original text. Required if accountHolderType is INDIVIDUAL.
middleName String(200)
- SHA256 of original text.
companyName String(200)
- SHA256 of original text. Required if accountHolderType is CORPORATE.
cardNumber String(64) Required
- SHA256 of original card number.
expiryMonth String(2) Required
- Card expiration month (1–12).
- Example value: 09
expiryYear String(4) Required
- Card expiration year.
- Example value: 2027
memo String(128)
- Transfer description or note.
- Example value: Bonus
notifyUrl String(200)
- URL where the merchant receives notifications.
- Example value: http://yoursite.com/api/notification
failDes String(200)
- Cause of order failure.
- Example value: -
bankReference String(128)
- Bank reference number.
payerFeeAmount Money Required
- Fee paid by the payer.
- Example value:
  { "amount": 0, "currency": "AED" }
payerFeeMemberId String(32) Required
- ID of the party paying the fee.
- Example value: 200000429066
paidTime Date Required
- Time of deduction.
refundedTime Date
- Time of refund.

Response Sample

HTTP Headers

{
    "sign": "Yv+C2lOQmfERdm5GF9b2V4Y98HmX/6CFyconeOW36AoPqcb7InRcP9E5GnvJLfMoCScuNP4FBdJ5tJpL0A7yPHUMfxARi05jFRSMG97JJazDbWTbRkNM1ZupmTubhUvxvRCgvJp1k0c5yrHph+F+++W5eYho92xnkNgd62BS27i0iDRGzGSmsaPpK7MFcdlvnbbnmDZZJ0LH6RhYiJLYKl+znllQx3jNfCRjV28o22FZ35Q43mZTsS4uAZWbZ/KfaqWoV3sN62Cjj8DSg3mD6GCGWSVbxLq58DUxAq+6GwJ7Gj0Dc9nMXP3gnFW7dodQ9AjL2iHnH6Zh1Pw2D5/ung=="
}

HTTP Body

{
    "body": {
        "transferToBankCard": {
            "amount": {
                "amount": 0.1,
                "currency": "AED"
            },
            "partnerId": "200000429066",
            "notifyUrl": "http://yoursite.com/api/notification",
            "memo": "Bonus",
            "createdTime": 1741917501666,
            "payerFeeAmount": {
                "amount": 0,
                "currency": "AED"
            },
            "payerFeeMemberId": "200000429066",
            "orderNo": "131741917501042130",
            "merchantOrderNo": "7a5b47a4-1824-4a4d-b581-9b0ebd5dd436",
            "product": "Transfer Bank Card",
            "status": "CREATED",
            "paidTime": 1741917502000,
            "accountHolderType": "INDIVIDUAL",
            "cardNumber": "6b59af6dcc4fb841d5f053a852ed917fd5eecad0cc2c3e3507540c065f520a4c",
            "expiryMonth": "08",
            "expiryYear": "2028",
            "firstName": "c6f27629d041725bb227a0d718641d220d69356cd82b3b7230f1d0dff950de5f",
            "lastName": "15d6dacb4fbda825195e5873c175a9b093daa32345c708ac18411365f6fc6038",
            "middleName": "15d6dacb4fbda825195e5873c175a9b093daa32345c708ac18411365f6fc6038"
        }
    },
    "head": {
        "applyStatus": "SUCCESS",
        "code": "0",
        "msg": "SUCCESS",
        "traceCode": "974825"
    }
}

Response Codes

Code	Message	Cause	Workaround
0	SUCCESS	Request successful	-
400	INVALID_PARAMETER	Invalid request parameters	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too early	Adjust request time
400	REQUESTTIME_TOO_LATER	Request time is too late	Adjust request time
402	RATE_LIMIT_REJECT	Too many requests	Reduce request frequency
403	UNAUTHORIZED	API not authorized	Contact PayBy
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact PayBy
500	SYSTEM_ERROR	System error	Contact PayBy, retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later
601	RISK_FAIL	Risk control validation failed	Adjust business parameters
62002	ORDER_FAILURE	Order has failed	Use different merchant order number
62016	MERCHANT_ORDER_NO_EXIST	Duplicate order number with different parameters	Use different order number
62026	PRODUCT_IS_NOT_APPLIED	Product not activated	Apply for product access
62028	ORDER_SUCCESS	Order already successful	Use different merchant order number
62029	ORDER_CREATED	Order already created	Use different merchant order number

Bank Card Transfer

Overview​

Order Status​

API URL​

Request​

HTTP Headers​

HTTP Body​

Request Sample​

Response​

HTTP Headers​

HTTP Body​

Response Sample​

HTTP Headers​

HTTP Body​

Response Codes​

Overview

Order Status

API URL

Request

HTTP Headers

HTTP Body

Request Sample

Response

HTTP Headers

HTTP Body

Response Sample

HTTP Headers

HTTP Body

Response Codes